Skip to content

Improve regularisation documentation and add ADMT demo - #427

Merged
jacklovell merged 24 commits into
developmentfrom
feature/admt-demo
Aug 20, 2026
Merged

Improve regularisation documentation and add ADMT demo#427
jacklovell merged 24 commits into
developmentfrom
feature/admt-demo

Conversation

@jacklovell

@jacklovell jacklovell commented Mar 11, 2024

Copy link
Copy Markdown
Member
  • Add a Regularisation section to the tomography documentation, describing the functionality inside the admt_utils module.
  • Fixup the docstrings in admt_utils.
  • Add calculation of "skewed" second derivative operators, which operate along the diagonals of the grid.
  • Add a bolometer diagonstic system to Generomak.
  • Add a new example using the Generomak bolometers and the regularisation operators to perform isotropic and ADMT inversions.
  • Add a regularised NNLS function which uses sparse matrices.
  • Enable the functions in admt_utils to optionally output sparse matrices depending on the input.

Fixes #382 and #380

* Add a Regularisation section to the tomography documentation,
  describing the functionality inside the admt_utils module.
* Fixup the docstrings in admt_utils.
* Add calculation of "skewed" second derivative operators, which
  operate along the diagonals of the grid.
* Add a bolometer diagonstic system to Generomak.
* Add a new example using the Generomak bolometers and the
  regularisation operators to perform isotropic and ADMT inversions.

@vsnever vsnever left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jacklovell, very valuable demo. A similar regularisation is used in ITER divertor bolometry to reconstruct the radiation power density profile. Generomak also receives the first diagnostics, which in itself is great.

I think the changelog should reflect that this demo has been added, and also that the bolometric diagnostic model has been added to Generomak.

I also have some comments and a few suggestions.

Comment thread docs/source/tools/tomography.rst Outdated
Comment thread demos/observers/bolometry/admt_tomographic_inversion.py
Comment thread demos/observers/bolometry/admt_tomographic_inversion.py
Comment thread cherab/generomak/diagnostics/bolometers.py Outdated
Comment thread cherab/generomak/diagnostics/bolometers.py Outdated
Comment thread cherab/generomak/diagnostics/bolometers.py Outdated
Comment thread cherab/generomak/diagnostics/bolometers.py Outdated
Comment thread cherab/tools/inversions/admt_utils.py
Comment thread demos/observers/bolometry/admt_tomographic_inversion.py
jacklovell and others added 6 commits May 18, 2026 09:39
* Fix the series of transforms to position and orient the bolometer
  cameras.
* Update geometry parameters such that the lines of sight all follow a
  consistant convention and specify the channel ordering in the
  docstring. This required adding the ability to rotate the sensors
  about the viewing axis to reverse the channel order of the
  horizontal-poloidal camera.
* Correct the docstring of load_bolometers to specify the correct
  number of 4-channel sensors in each camera.
* Expand docstrings and comments to better describe the intricacies of
  setting up the bolometer geometry.
* More thorough commenting of the function to make it easier to follow
  what is going on and why.
* Exploit the sparsity of the derivative opreators but using a
  dictionary-of-keys representation instead of dense numpy arrays. A
  dictionary is faster to insert single elements into inside the loop
  than a numpy array too.
* Remove the `np.isnan` checkc which are slow for single elements,
  replace with a cheap check for `None`.
* Support returning the operators as Scipy sparse arrays for use
  downstream. Default to returning as Numpy arrays for backwards
  compatibility.

These changes result in an order of magnitude speedup in this function.
This is done automatically if the derivative operators are
sparse. A dense operator is returned otherwise.
An alternative to `invert_regularised_nnls` using sparse weight and
penalty matrices. The numerical algorithm used is slightly different
to `scipy.optimize.nnls`, as it uses the TRF variant of a bounded
`scipy.optimize.lsq_linear` with the lower bound set to 0 to enforce
positivity. Since the results differ due to floating point precision,
the sparse variant is implemented as a separate function to maintain
backwards compatibility.
* Produce additional inversions which incorporate Generomak's
  tangentially-viewing channels, for comparison with the poloidal-only
  inversions.
* Correctly scale the emissivity.
* Fix removing the ray transfer grid from the world before
  forward-modelling the bolometer measurements.
* Better explain why we're building the 1D <-> 2D maps by hand instead
  of just using the ray transfer matrix capabilities directly: this is
  for generality.
* Use the sparse variant of the NNLS inversion for speed and memory
  efficiency. The grid is large enough for this to be worthwhile.
@jacklovell jacklovell changed the title WIP: Improve regularisation documentation and add ADMT demo Improve regularisation documentation and add ADMT demo Jul 15, 2026
@Mateasek Mateasek mentioned this pull request Jul 16, 2026
12 tasks
Comment thread cherab/generomak/diagnostics/bolometers.py
Comment thread cherab/generomak/diagnostics/bolometers.py
Comment thread cherab/tools/inversions/nnls.py
This makes it easier for users to explore the geometry and potentially
even edit it for testing purposes.
This is a more common term in the literature for a bolometer unit
integrating several (typically 4) channels.
* The 1D-to-2D and 2D-to-1D maps are the inverse of one another, so
  one can be computed from the other. Depending on how the end user
  forms their inversion grid it may be simpler to calculate the
  1D-to-2D or the 2D-to-1D, so allow the caller to pass either and
  compute any missing mapping. If the caller already has both
  mappings (machine packages like cherab-jet, cherab-mastu and
  cherab-aug already generate both) then accept both too.
* Add tests for auto-computing missing mappings.
* Tests uncovered a bug converting the Dyy sparse operator to dense
  when `sparse=False` was passed: fix that and complete test coverage
  for `admt_utils`.
* Simplify the ADMT script by only computing the 1D-to-2D map as this
  is fairly trivially obtained from the Ray Transfer object.
@jacklovell
jacklovell requested a review from skuba31 July 31, 2026 16:19
@jacklovell

Copy link
Copy Markdown
Member Author

I've implemented the changes from both reviews now: thanks to @vsnever and @skuba31. I am going to hold firm on the formulism in generate_derivative_operators though, as I think the benefits of sparseness and explicitness outweigh any potential performance gains or loss of generality of the vectorized version Vlad proposed before the iterative improvements from the reviews. As a compromise the function is now better commented and the interface is a bit easier to use for callers as reflected in the demo.

Once this is approved I'll do a squash merge as the commit history is longer than necessary to keep going forwards.

Comment thread cherab/generomak/diagnostics/bolometers.py
Comment thread demos/observers/bolometry/admt_tomographic_inversion.py Outdated

@skuba31 skuba31 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work @jacklovell . I think that the documentation and code readability is significantly improved. The sparse support and ADMT demo are very useful additions. I have added a few minor comments for consideration before final approval.

@skuba31 skuba31 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I consider this PR to be ready for merge now.

@jacklovell
jacklovell merged commit fcdeaf7 into development Aug 20, 2026
12 checks passed
@jacklovell
jacklovell deleted the feature/admt-demo branch August 20, 2026 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants